Руководство для начинающих¶

Пререквизиты¶

Для выполнения примера требуются:

• установленный Docker-образ Tarantool DB;

• приложение Docker compose;

• утилита TT CLI;

• исходные файлы примера up_with_docker_compose.

  Примечание

  Есть два способа получить исходные файлы примера:

  • Архив с полной документацией Tarantool DB, полученный по почте или скачанный в личном кабинете tarantool.io. Пример архива: tarantooldb-documentation-1.0.0.tar.gz. Пример up_with_docker_compose расположен в таком архиве в директории ./doc/examples/up_with_docker_compose/.

  • Отдельный архив up_with_docker_compose.tar.gz, скачанный c сайта Tarantool.

Запуск стенда¶

Запустить кластер Tarantool DB можно с помощью следующей команды:

docker compose up -d --build

Ответ выглядит так:

[+] Running 11/11
 ⠿ Network up_with_docker_compose_tarantooldb_network          Created                                                                              0.1s
 ⠿ Container up_with_docker_compose-tarantool-storage-1-msk-1  Started                                                                              5.0s
 ⠿ Container up_with_docker_compose-tarantool-router-spb-1     Started                                                                              3.8s
 ⠿ Container up_with_docker_compose-tarantool-router-msk-1     Started                                                                              5.2s
 ⠿ Container up_with_docker_compose-etcd3-1                    Started                                                                              3.7s
 ⠿ Container up_with_docker_compose-tarantool-storage-1-spb-1  Started                                                                              4.9s
 ⠿ Container up_with_docker_compose-etcd1-1                    Started                                                                              4.4s
 ⠿ Container up_with_docker_compose-etcd2-1                    Started                                                                              5.3s
 ⠿ Container up_with_docker_compose-tarantool-storage-2-spb-1  Started                                                                              5.1s
 ⠿ Container up_with_docker_compose-tarantool-storage-2-msk-1  Started                                                                              5.1s
 ⠿ Container up_with_docker_compose-user-host-1                Started                                                                              6.4s

Создание спейса через веб-интерфейс¶

После запуска с кластером Tarantool DB можно работать через веб-интерфейс, коннекторы или консоль.

Создайте спейс, с которым вы будете работать в дальнейшем. Для этого:

1. Откройте в браузере веб-интерфейс любого из узлов Tarantool DB (http://localhost:8081).

2. Перейдите на вкладку Code.

3. На вкладке Code создайте папку migrations. Внутри папки migrations создайте папку source. Названия этих папок менять нельзя.

4. В папке source создайте файл с любым названием, например create_space_bands.lua. Добавьте в файл следующий код:

   local function up()
       local utils = require('migrator.utils')
   
       box.schema.space.create('bands', {if_not_exists = true})
       box.space.bands:format({
           { name = 'id', type = 'integer' },
           { name = 'bucket_id', type = 'unsigned' },
           { name = 'band_name', type = 'string' },
           { name = 'year', type = 'integer' },
       })
       box.space.bands:create_index('primary_key', { parts = {'id'}, if_not_exists = true})
       box.space.bands:create_index('bucket_id', { parts = {'bucket_id'}, unique = false, if_not_exists = true})
   
       utils.register_sharding_key('bands', {'id'})
         
       return true
   end
   
   return {
       up = up,
   }
   

5. Нажмите кнопку Apply.

6. Запустите миграции с помощью следующей команды:

   curl -X POST http://localhost:8081/migrations/up
   

   Здесь:

   • localhost:8081 – адрес экземпляра.

   Ответ выглядит так:

   {"applied":["create_space_bands.lua"]}
   

В результате на всех узлах кластера создан шардированный спейс bands. Содержимое спейса на каждом узле кластера можно просмотреть в веб-интерфейсе во вкладке Space Explorer.

Пример загрузки конфигурации и клиентского кода через API можно найти в разделе Запуск кластера через Docker compose.

Запросы к данным c помощью модуля CRUD¶

Подключитесь к узлу кластера с помощью утилиты tt. Команда tt connect открывает интерактивную консоль Tarantool, позволяющую работать с базой данных:

tt connect admin:secret-cluster-cookie@localhost:3301

Теперь добавьте в спейс bands несколько кортежей:

crud.insert_object('bands', {id = 1, band_name = 'Roxette', year = 1986})
crud.insert_object('bands', {id = 2, band_name = 'Scorpions', year = 1965})
crud.insert_object('bands', {id = 3, band_name = 'Ace of Base', year = 1987})
crud.insert_object('bands', {id = 4, band_name = 'The Beatles', year = 1960})

После этого просмотрите содержимое спейса с помощью операции crud.select():

crud.select('bands')

Вывод выглядит так:

---
- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
  rows:
  - [1, 12477, 'Roxette', 1986]
  - [2, 21401, 'Scorpions', 1965]
  - [3, 11804, 'Ace of Base', 1987]
  - [4, 28161, 'The Beatles', 1960]
- null
...

Теперь прочитайте запись, у которой id = 1:

crud.get('bands', 1)
---
- rows:
  - [1, 12477, 'Roxette', 1986]
  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
- null
...

Теперь обновите запись с id = 3, увеличив значение на единицу:

crud.update('bands', 3, {{'+', 'year', 1}})
---
- rows:
  - [3, 11804, 'Ace of Base', 1988]
  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
- null
...

Удалите запись с id = 4:

crud.delete('bands', 4)
---
- rows:
  - [4, 28161, 'The Beatles', 1960]
  metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
- null
...

Просмотрите еще раз содержимое спейса bands:

crud.select('bands')
---
- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
  rows:
  - [1, 12477, 'Roxette', 1986]
  - [2, 21401, 'Scorpions', 1965]
  - [3, 11804, 'Ace of Base', 1988]
- null
...

Здесь:

• значение year в кортеже с id = 3 увеличилось на 1;

• запись с id = 4 успешно удалена.

Проверка работы кластера при отказах¶

Отказ – это любое событие, которое приводит к недоступности узла кластера. Примеры отказов: потеря связи с узлом, выход из строя оборудования с расположенным на нем узлом.

Этот пример можно выполнить на локально развёрнутом кластере двумя способами:

• через Docker compose;

• через утилиту tt.

docker compose stop tarantool-storage-1-msk
docker compose stop tarantool-storage-2-spb

tt stop tarantooldb:storage-1-msk
tt stop tarantooldb:storage-2-spb

crud.select('bands')

---
- metadata: [{'name': 'id', 'type': 'integer'}, {'name': 'bucket_id', 'type': 'unsigned'},
    {'name': 'band_name', 'type': 'string'}, {'name': 'year', 'type': 'integer'}]
  rows:
  - [1, 12477, 'Roxette', 1986]
  - [2, 21401, 'Scorpions', 1965]
  - [3, 11804, 'Ace of Base', 1988]
- null
...

Изменение конфигурации кластера¶

Перед изменением конфигурации кластера, например, при добавлении новых наборов реплик или перераспределении данных между узлами, требуется выполнить несколько предварительных шагов. Эти шаги необходимы для обеспечения стабильной работы запросов к данным.

Перед изменением конфигурации кластера:

1. Приостановите любые DML-операции (insert, update, delete) во всех компонентах системы.

2. Выполните масштабирование или инициируйте ребалансировку.

3. Дождитесь полного завершения процесса миграции бакетов.

4. На всех роутерах выполните сброс маршрутов:

   vshard.router._route_map_clear()
   

5. Возобновите выполнение DML-операций.

После этого вы можете выполнить изменение конфигурации кластера.

Остановка стенда¶

Остановить стенд можно так:

docker compose down